Azure Search - Part 6 (使用 REST API 上傳資料至 Azure Search)

可以上傳資料到 Azure Search index 的方式有二個：

1. 推送資料至 index(Push data to an index)

   • 使用 .NET SDK 或 REST API
   • 可保持較高的資料一致性
   • 可個別或是批次上傳

2. 拉資料進 index(Pull data into an index)

   • 會檢查支援的資料來源並主動上傳
   • 可以辨識新 document 、也可追蹤現有 document 的變更，減少主動管理 index 資料
   • 透過 indexers 支援 Blob 儲存體 (預覽)、DocumentDB、Azure SQL Database 和 Azure VM 上的 SQL Server

今天來試試 REST API 的用法，透過 REST API 上傳資料就是 將新增、修改或是刪除的 document 放在 request body,發出 HTTP POST request 到 index endpoint 的 URL .

準備 API Key

Azure Search Service Key

1. 登入 Azure Portal
2. 開啟 Azure Search
3. 點擊 金鑰

4. 取得 主要管理金鑰 或是 次要管理金鑰

兩者皆可用來建立 index

1. 決定要用哪一種 action 進行 index

資料 --> document(含有 key) + property(action:Upload,Merge,MergeOrUpload,Delete) == json object --> value(陣列) ==> value 放在 request body 中,HTTP POST 至 Azure Search Service 的 index endpoint 的 URL

1. 資料輸出成 JSON object
2. JSON object 由 document 與 property 組成
3. 一個或多個 JSON object 組成 value
4. value 放在 request body 透過 HTTP POST 至 index endpoint 的 URL

Action|說明|必要欄位|注意事項
-|
Upload|document 不存在就建立,存在就取代|key,及其他想指定的欄位|在 更新 document 時，未指定的欄位會設定為 null,即使之前已設定過
Merge|使用指定的欄位更新現有 document。 如果 document 不存在於 index 中，merge 就會失敗。|KEY,及想更新的欄位|merge 中指定的任何欄位將取代文件中現有的欄位，可用來移除個別欄位
MergeOrUpload|有指定 key 的 document 已存在 index 中，則 Merge,否則就 Upload|key,及其他想指定的欄位|-
Delete|從 index 中移除指定的 document|key|除了 key 之外都會被忽略

2. 建立 HTTP request 跟 request body

2-1. request 和 request header

1. URL

• Service name
• Index name
• API 版本

我在範例有看到 2016-09-01 版本，但正式文件跟 Azure Portal 都還沒有

```
https://[search service].search.windows.net/indexes/hotels/docs/index?api-version=2015-02-28
```

2. header
   • Content-Type
   • api-key

Content-Type: application/json
api-key: [admin key]

2-2. request body

• 使用 json
• 包含 一個 value object
• value 中有多個 document
• document 需要有 action("@search.action") 及 key, 還有其他想指定的欄位
• 每個 request 不得超過 1000 document 或是 16 MB (看哪個先滿足)

{
    "value": [
        {
            "@search.action": "upload",
            "hotelId": "1",
            "baseRate": 199.0,
            "description": "Best hotel in town",
            "description_fr": "Meilleur hôtel en ville",
            "hotelName": "Fancy Stay",
            "category": "Luxury",
            "tags": ["pool", "view", "wifi", "concierge"],
            "parkingIncluded": false,
            "smokingAllowed": false,
            "lastRenovationDate": "2010-06-27T00:00:00Z",
            "rating": 5,
            "location": { "type": "Point", "coordinates": [-122.131577, 47.678581] }
        },
        {
            "@search.action": "upload",
            "hotelId": "2",
            "baseRate": 79.99,
            "description": "Cheapest hotel in town",
            "description_fr": "Hôtel le moins cher en ville",
            "hotelName": "Roach Motel",
            "category": "Budget",
            "tags": ["motel", "budget"],
            "parkingIncluded": true,
            "smokingAllowed": true,
            "lastRenovationDate": "1982-04-28T00:00:00Z",
            "rating": 1,
            "location": { "type": "Point", "coordinates": [-122.131577, 49.678581] }
        },
        {
            "@search.action": "mergeOrUpload",
            "hotelId": "3",
            "baseRate": 129.99,
            "description": "Close to town hall and the river"
        },
        {
            "@search.action": "delete",
            "hotelId": "6"
        }
    ]
}

3. HTTP Response Code

Status Code|說明| Response Body
-|
200|成功建立|{ "value": [ { "key": "unique_key_of_document", "status": true, "errorMessage": null }, ... ]}
207|至少有一個項目未成功，通常表示 loading 即將到達上限，可建立暫停及重試機制|{ "value": [ { "key": "unique_key_of_document", "status": false, "errorMessage": "The search service is too busy to process this document. Please try again later." }, ... ]}
429|index 的 document 數量已達上限|-
503|所有項目皆未成功，表示系統已過載|-

REST API 對於沒有 .NET SDK 的環境是另個方便的選擇，使用上也很容易.

參考資料

1. 使用 REST API 將資料上傳至 Azure 搜尋服務